Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /

Chapter 6 - Printing Resources / Printing Resources Reference

Resources Used Only in Printer Drivers

The Dialog Control ('dctl') Resource

You need to include a dialog control resource to define control items for the print dialog boxes used with Macintosh Printing Manager applications. This resource provides you with a means of mapping the behavior of items in an item list ('DITL') resource to fields in the universal print structure that QuickDraw GX uses for compatibility with Macintosh Printing Manager applications. The resource consists of a list of action types, each of which maps to one or more items in the item list resource and to a location in the universal print record.

The item list resource is described in Inside Macintosh: Macintosh Toolbox Essentials. The universal print structure is described in the section "The Universal Print Structure" beginning on page 4-12 in the chapter "Printing Messages." Figure 6-18 shows the structure of the dialog control resource.

Figure 6-18 The dialog control resource

The dialog control resource contains a count of the control-item entries and an array of control-item definitions.

• Maximum item count. The maximum item count for the item list resource.
• Number of array entries. The number of control-item definitions that follow.

Each control item definition has a unique item-key value and some number of values.

• Item key. The type of control item. The values that you can use in this field are shown in Table 6-22.
• Item values. The values that are needed to define the control item. The number and types of the values that you include in this field depend on the type of item that you are defining, as shown in the individual action sections beginning on page page 6-55.

The types of control items that you can define in a dialog control resource are shown in Table 6-22. Each item is described in more detail in the sections that follow the table.

Table 6-22 Control item types

Item type	Value	Explanation
Button	1	Implements the Cancel button
Cluster	2	Implements options that are presented to the user as a series of radio buttons
Copies	3	Implements the editable text item into which the user enters the number of copies to be printed
DialogBtn	4	Implements dialog boxes on top of the current dialog box
Frill	5	Used to draw the double-line bar, the version number, the heavy outline around the default button, and the printer name in the title of the dialog box
Moof	6	Draws Moof, the circus trick dog, which is displayed in the Page Setup dialog box to denote page orientation
OKButton	7	Implements the OK button
Orientation	8	Implements the orientation icon buttons
PageRange	9	Allows the user to specify the range of pages to be printed
PaperSizes	10	Implements selection of paper sizes by the user
Scale	11	Implements the print-scaling (Reduce/Enlarge) option
Toggle	12	Implements checkboxes that set and clear various bits in the iFlags field of the universal print structure

A dialog control resource can contain a number of actions, each of which is named by its type and followed by a number of values. Listing 6-17 shows two definitions of a dialog control resource from the ImageWriter II printer driver.

Listing 6-17 Two examples of a dialog control resource

resource 'dctl' (-8192, sysHeap, purgeable) {
   20,
   {
   Button { 2, cancel },
   Frill { 4, line },
   PaperSizes { 0, 0, { 6, 7, 8, 9, 10, 11 } },
   Orientation { 13, 14, 0, 0 },

   Toggle { 16, bPreciseBitmap },
   Toggle { 17, bUser0 },
   Toggle { 18, bBiggerPages },
   
   Frill { 19, version },
   Frill { 20, default },
   }
};
resource 'dctl' (-8191, sysHeap, purgeable) {
   21,
   {
   Button { 2, cancel },
   Frill { 4, line },
   Cluster { quality, { 6, 7, 8 } },
   PageRange { 10, 11, 12, 14},
   Copies { 16 },
   Cluster { feed, { 18, 19 } },
   
   Frill { 20, version },
   Frill { 21, default },
   }
};

The following sections describe the values that you need to specify in the dialog control resource for each item type.

Button Actions

You use the button (Button) action-item type to implement the Cancel button in the Print dialog box used with Macintosh Printing Manager applications. When the user selects this button, QuickDraw GX automatically restores the values in the universal print structure to what they were when the dialog box was created. This action uses two values:

• Item ID. The integer ID of the item in the item list to which this button pertains.
• Button kind. The kind of button that this represents. At this time, you can only use this item type to define Cancel buttons. You use the integer constant cancel to do this.

Listing 6-17 on page 6-54 contains two examples of button actions.

Cluster Actions

You use the cluster (Cluster) action-item type to implement clusters of radio buttons. When the user selects one of the radio buttons, QuickDraw GX automatically updates the corresponding value in the universal print structure. This action uses two values:

• Cluster type. The kind of item that the cluster is used to define. This is one of the integer constants shown in Table 6-23.
• Cluster items. The IDs of the items to which the cluster corresponds.

Table 6-23 shows the constants that you can use to define what kind of item the radio button cluster is defining. Listing 6-17 contains an example of a cluster action.

Table 6-23 Cluster type constants for the dialog control resource

Cluster type	Value	Explanation
feed	0	Defines the feed mode used for the print job by filling in the feed field in the universal print structure
quality	1	Defines the print-quality mode used by filling in the qualityMode field in the universal print structure
coverPage	2	Defines the type of cover page to print for the print job by filling in the coverPage field in the universal print structure
firstPage	3	Defines which of the printer's paper trays is used as the first paper tray for this print job by filling in the firstTray field in the universal print structure
restPage	4	Defines the other paper tray for this print job by filling in the remainingTray field in the universal print structure
headMotion	5	Defines the type of print-head motion to use for the print job by filling in the headMotion field in the universal print structure
createFile	6	Defines the type of file to save for this print job by filling in the saveFile field in the universal print structure
user0	7	Reserved to allow the driver to define its own clusters and fill in the userCluster1 field in the universal print structure
user1	8	Reserved to allow the driver to define its own clusters and fill in the userCluster2 field in the universal print structure
user2	9	Reserved to allow the driver to define its own clusters and fill in the userCluster3 field in the universal print structure

Copies Actions

You use the copies (Copies) action-item type to implement the editable text item into which the user enters the desired number of print copies. When the user types a value into this field, QuickDraw GX verifies that the number is between 1 and 9999 and then stores that value in the actualCopies field in the universal print structure. This action uses one value:

• Item ID. The ID of the item to which this action pertains.

Listing 6-17 on page 6-54 contains an example of the copies action type.

Dialog-Button Actions

You use the dialog-button (DialogBtn) action-item type to implement dialog boxes that appear on top of the current dialog box. For example, in the LaserWriter printer driver, the Options button in the style dialog box displays the dialog box with Moof in it on top of the style dialog box. When the user selects the item, QuickDraw GX brings up the specified dialog box, which can itself contain any of the action-item types in it. This action uses three values:

• Item ID. The ID of the item to which this action pertains.
• Dialog ID. The ID of the dialog resource to display when this item is selected by
  the user.
• Control ID. The ID of the dialog control resource for the dialog box that is displayed when this item is selected by the user.

Frill Actions

You use the frill (Frill) action-item type to implement informational and decorative objects in the dialog box. This action uses two values:

• Item ID. The ID of the item to which this action pertains.
• Frill type. The type of frill. This is one of the integer values shown in Table 6-24.

  Table 6-24 Frill type constants for the dialog control resource

  Frill type	Value	Explanation
  line	0	Used to draw the double-line bar in the dialog box.
  version	1	Used to draw the version number in the dialog box.
  default	2	Used to draw the heavy outline under the default button in the dialog box.
  printerName	3	Used to draw the printer name in the dialog box. This item must be a static text item.

Listing 6-17 on page 6-54 contains several examples of frill actions.

Moof Actions

You use the Moof (Moof) action-item type to display Moof, the circus trick dog, as is done when the orientation of the page is displayed in the Page Setup dialog box. This action uses one value:

• Item ID. The ID of the item in which Moof is drawn when the dialog box is initialized.

Confirm-Button Actions

You use the confirm-button (OkButton) action-item type to implement the OK button in a dialog box. This item is only needed if there is a Create File cluster that needs to change the name of the OK button for printing (to switch the name of the OK button depending on whether the user is printing or saving a file). This action uses three values:

• Item ID. The ID of the OK button item. This value must be 1.
• String ID 1. The ID of the string resource to display for the "Print" choice.
• String ID 2. The ID of the string resource to display for the "Save" choice.

Orientation Actions

You use the orientation (Orientation) action-item type to implement the orientation icon buttons. You can use up to four different buttons to establish the value of the orientation field in the universal print structure. QuickDraw GX assumes that the driver contains as many icon ('ICON') resources as there are nonzero entries in this item definition. QuickDraw GX also assumes that the icon resource IDs start at 0 and increase by 1. This action uses four values:

• Portrait item ID. The ID of the portrait orientation item.
• Landscape item ID. The ID of the landscape orientation item.
• Alternate portrait item ID. The ID of the rotated portrait orientation item.
• Alternate landscape item ID. The ID of the rotated landscape orientation item.

Page-Range Actions

You use the page-range (PageRange) action-item type to implement the page-range selection. When the user enters page values in the "From" and "To" fields, QuickDraw GX updates the firstpage and lastPage values in the universal print structure. This action uses four values:

• All pages button ID. The ID of the "All Pages" button.
• Range button ID. The ID of the "Range" button.
• From field ID. The ID of the "From" or first-page editable text field.
• To field ID. The ID of the "To" or last-page editable text field.

Listing 6-17 on page 6-54 contains an example of a page-range action in a dialog control resource.

Paper-Size Actions

You use the paper-size (PaperSizes) action-item type to implement selection of paper sizes for a print job. This action has two values and an array of item IDs:

• Pop-up item ID. The item ID of the paper-sizes pop-up menu.
• Pop-up radio item ID. The ID of the paper-sizes pop-up menu.
• Item IDs. An array of IDs, one per radio button item that is referenced by this action.

Listing 6-17 on page 6-54 contains an example of a paper-size action item in a dialog control resource.

Scale Actions

You use the scale (Scale) action-item type to implement the reduce and enlarge option in the Page Setup dialog box. This action uses two values:

• Edit ID. The ID of the editable text item that contains the scaling value.
• Arrow ID. The ID of the item that controls the up and down actions on the
  scaling value.
• Scaling table ID. The resource ID of the scaling table resource that defines the scaling values for this action item. The scaling table resource is described on page 6-61.

Toggle Actions

You use the toggle (Toggle) action-item type to implement the checkboxes that set and clear the flags in the options field of the universal print structure. This action uses
two values:

• Item ID. The ID of the item to which this action pertains.
• Toggle type. The kind of toggle item to which this action pertains. You can combine any of the integer constants from Table 6-25 to form the value of this field. When you combine values and the user clicks the checkbox, all of the flags associated with the value are set.

  Table 6-25 Toggle action-item flags for the dialog control resource

  Toggle item type	Value	Explanation
  bPreciseBitmap	0x0001	The driver needs to format pages as tall-adjusted for the Apple ImageWriter family of printers, and the driver needs to use precise bitmaps for the Apple LaserWriter family of printers. This is the same as the gxPreciseBitmap value described on page 4-15 in the chapter "Printing Messages."
  bBiggerPages	0x0002	The driver needs to not apply gaps if printing this job to one of the Apple ImageWriter family of printers, and the driver needs to use a large print area for the Apple LaserWriter family of printers. This is the same as the gxBiggerPages value described on page 4-15 in the chapter "Printing Messages."
  bGraphicSmoothing	0x0004	The driver needs to perform graphics smoothing on the Apple LaserWriter family of printers. This is the same as the gxGraphicSmoothing value described on page 4-15 in the chapter "Printing Messages."
  bTextSmoothing	0x0008	The driver needs to perform text smoothing for this print job. This is the same as the gxTextSmoothing value described on on page 4-15 in the chapter "Printing Messages."
  bFontSubstitution	0x0010	The driver needs to perform font substitution for this print job. This is the same as the gxFontSubstitution value described on page 4-15 in the chapter "Printing Messages."
  bInvert	0x0020	The driver needs to invert the printed image (convert white to black and black to white) for this print job. This is the same as the gxInvertPage value described on page 4-15 in the chapter "Printing Messages."
  bFlipHoriz	0x0040	The driver needs to flip pages horizontally for this print job. This is the same as the gxFlipPageHoriz value described on page 4-15 in the chapter "Printing Messages."
  bFlipVert	0x0080	The driver needs to flip pages vertically for this print job. This is the same as the gxFlipPageVert value described on page 4-15 in the chapter "Printing Messages."
  bColorMode	0x0100	This print job uses color printing. This is the same as the gxColorMode value described on page 4-15 in the chapter "Printing Messages."
  bBidirectional	0x0200	This print job uses bidirectional printing. This is the same as the gxBidirectional value described on page 4-15 in the chapter "Printing Messages."
  bUser0	0x0400	Available for driver-defined options.
  bUser1	0x0800	Available for driver-defined options.
  bUser2	0x1000	Available for driver-defined options.
  bReserved0	0x2000	Reserved for future options.
  bReserved1	0x4000	Reserved for future options.
  bReserved2	0x8000	Reserved for future options.

Listing 6-17 on page 6-54 contains several examples of toggle action items in a dialog control resource.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help